[ENH] Add DWI recommended metadata #2309

kabilar · 2026-01-16T05:35:52Z

for more information, see https://pre-commit.ci

codecov · 2026-01-16T05:40:17Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 82.81%. Comparing base (1fd10bb) to head (6851fa9).

Additional details and impacted files

@@           Coverage Diff           @@
##           master    #2309   +/-   ##
=======================================
  Coverage   82.81%   82.81%           
=======================================
  Files          22       22           
  Lines        1693     1693           
=======================================
  Hits         1402     1402           
  Misses        291      291

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

effigies · 2026-01-16T18:01:07Z

src/modality-specific-files/magnetic-resonance-imaging-data.md

+  "DiffGradientDuration": 11.0,
+  "DiffGradientSeparation": 15.2,


We don't generally use abbreviations. I would say either "DiffusionGradientDuration/Separation" or "GradientDuration/Separation". I would probably prefer the latter if the terms are unambiguous within a diffusion context and wouldn't refer to something else in another context BIDS is likely to touch on.

Thanks @effigies. Just avoid any potential future confusion, I would prefer "DiffusionGradientDuration/Separation".

@ayendiki @Tinggong What do you think?

I don't necessarily like the word "separation", which to me implies the interval between the end of one pulse and the beginning of the other pulse. Other words to potentially use here are "interval", or "offset". I do wonder if given their prevalence in the literature, BigDelta and SmallDelta wouldn't be clearer. Also, I do believe that this is a redefinition of something that could already be captured by MixingTime: https://bids-specification.readthedocs.io/en/stable/glossary.html#mixingtime-metadata?

I see this as related to #2311

I'm not familiar with how diffusion sensitization plays out in a "double spin echo" diffusion weighted sequence, but are MixingTime and BigDelta really the same thing?

The timing parameters are defined quite differently for "double" or "twice refocused" spin echo sequences, see https://onlinelibrary.wiley.com/doi/10.1002/mrm.10308. IIUC (see Fig 1 therein), there is no "BigDelta" in these sequences, and the intensity of the gradients is somehow integrated across all those small deltas, so I think that's to be handled separately, maybe in the advanced dMRI BEP.

So then, the existing MixingTime is not appropriate here, right?

I am not too familiar with MixingTime but this paper declares the mixing time, gradient separation, and gradient duration as separate values:

...mixing time TM=173.0 ms, gradient separation Δ=185.8 ms and a gradient duration of δ=5.4ms.

tsalo · 2026-01-23T17:13:03Z

I believe that some large datasets have been using their own versions of this (e.g., HBCD has LargeDelta and SmallDelta), so it would be good to get input on the naming from some folks who might be doing something similar (@mharms, @Lestropie, @arokem).

mharms · 2026-01-23T18:06:56Z

BigDelta (rather than LargeDelta) and SmallDelta would be the commonly used colloquial terms.

What about sequences that might allow for differing deltas across the differing volumes? How would that be handled?

mharms · 2026-01-23T18:09:17Z

Also, are BIDS timing parameters no longer all specified in seconds? (This proposal was specifying these parameters in msec).

ayendiki · 2026-01-23T18:17:44Z

BigDelta (rather than LargeDelta) and SmallDelta would be the commonly used colloquial terms.

What about sequences that might allow for differing deltas across the differing volumes? How would that be handled?

That's exactly our use case for our imminent data release. There are 2 competing options right now: separate text files like bvec and bval, or a sequence of numbers in the JSON file. Would love to get a consensus that involves bvec, bval, TE, δ, Δ all being handled the same way.

mharms · 2026-01-23T18:23:48Z

Would love to get a consensus that involves bvec, bval, TE, δ, Δ all being handled the same way.

Well, the treatment of bvec and bval as separate text files is longstanding, and that presumably isn't going to change. Does the current standard support an array for TE, if the TE is changing as well?

effigies · 2026-01-23T18:24:29Z

Also, are BIDS timing parameters no longer all specified in seconds?

We have 42 fields with units s and only 3 with other time units (all ms):

󰅂 git grep 'unit: ' src/schema/objects/metadata.yaml | sed -e 's/: [ -]*/: /' | sort | uniq -c | sort -h 
      1 src/schema/objects/metadata.yaml: unit: cm
      1 src/schema/objects/metadata.yaml: unit: g/mL
      1 src/schema/objects/metadata.yaml: unit: mL
      1 src/schema/objects/metadata.yaml: unit: mL/s
      1 src/schema/objects/metadata.yaml: unit: mT.s/m
      1 src/schema/objects/metadata.yaml: unit: um
      1 src/schema/objects/metadata.yaml: unit: uT
      2 src/schema/objects/metadata.yaml: unit: arbitrary
      2 src/schema/objects/metadata.yaml: unit: cm/s
      2 src/schema/objects/metadata.yaml: unit: dB
      2 src/schema/objects/metadata.yaml: unit: MHz
      2 src/schema/objects/metadata.yaml: unit: mT/m
      3 src/schema/objects/metadata.yaml: unit: ms
      4 src/schema/objects/metadata.yaml: unit: ppm
      6 src/schema/objects/metadata.yaml: unit: degree
      6 src/schema/objects/metadata.yaml: unit: m
      8 src/schema/objects/metadata.yaml: unit: mm
     10 src/schema/objects/metadata.yaml: unit: Hz
     42 src/schema/objects/metadata.yaml: unit: s

There are two ASL metadata fields and one MRS field that use milliseconds (LabelingPulseDuration, LabelingPulseInterval, and EditPulse.PulseDuration). I don't know if there were discussions or if these flew under the radar. Possibly @HenkMutsaerts and @markmikkelsen will recall?

I think it does make sense to stick with seconds, but it's not unprecedented to use ms.

kabilar · 2026-01-23T18:29:03Z

What about sequences that might allow for differing deltas across the differing volumes? How would that be handled?

Hi @mharms, I filed #2320 to handle this case. But there is some subsequent discussion in #2302 related to this that is also summarized by @ayendiki above.

kabilar · 2026-01-23T18:36:29Z

Does the current standard support an array for TE, if the TE is changing as well?

Yes, TE does allow for an array of numbers. Please see Timing parameters.

kabilar · 2026-01-23T18:42:45Z

Also, are BIDS timing parameters no longer all specified in seconds? (This proposal was specifying these parameters in msec).

I think it does make sense to stick with seconds, but it's not unprecedented to use ms.

Happy to switch to seconds if that is common across BIDS. I opted for milliseconds here since that is how δ and Δ (and TE) are reported in manuscripts.

markmikkelsen · 2026-01-24T16:52:32Z

There are two ASL metadata fields and one MRS field that use milliseconds (LabelingPulseDuration, LabelingPulseInterval, and EditPulse.PulseDuration). I don't know if there were discussions or if these flew under the radar. Possibly @HenkMutsaerts and @markmikkelsen will recall?

I think it does make sense to stick with seconds, but it's not unprecedented to use ms.

@effigies: EditPulse.PulseDuration is always reported in ms in the MRS literature, but given the vast majority of units of time in BIDS are reported in s, I wouldn't be opposed to changing it to s.

markmikkelsen · 2026-01-24T16:55:59Z

It's like with EchoTime and RepetitionTime: I personally always report them in ms in my papers, but they are reported in s in BIDS.

markmikkelsen · 2026-01-24T16:57:27Z

I can start a separate PR for this if needed.

effigies · 2026-01-24T17:25:45Z

No, that would break backwards compatibility. Tools could probably figure out the scale by looking at the value, but it's not worth having one interpretation in one version and another in another.

…ication into dwi-parameters

kabilar · 2026-01-26T21:54:18Z

Hi all, thanks for the feedback. I have updated this pull request. Next I will update #2320.

src/modality-specific-files/magnetic-resonance-imaging-data.md

mharms · 2026-01-26T23:47:04Z

src/schema/objects/metadata.yaml

        format: participant_relative
+BigDelta:
+  name: BigDelta
+  display_name: Diffusion Gradient Separation


I'm not sure where/how these "display_name" fields show up, but I wonder if it should just be "Diffusion BigDelta"?

One place it shows up is in the Glossary under the Name field. How about the following?

Suggested change

display_name: Diffusion Gradient Separation

display_name: Diffusion Big Delta (Δ)

kabilar added 2 commits January 15, 2026 23:25

Add recommended DWI metadata

5ef201d

Update metadata

69fc18f

kabilar requested a review from erdalkaraca as a code owner January 16, 2026 05:35

[pre-commit.ci] auto fixes from pre-commit.com hooks

e81113f

for more information, see https://pre-commit.ci

kabilar mentioned this pull request Jan 16, 2026

Combined DWI scheme with different acquisition parameters #2302

Open

effigies added this to the 1.11.0 milestone Jan 16, 2026

kabilar mentioned this pull request Jan 22, 2026

[ENH] Add combined DWI scheme #2320

Open

effigies reviewed Jan 23, 2026

View reviewed changes

tsalo mentioned this pull request Jan 24, 2026

Consistently use seconds for metadata fields instead of milliseconds bids-standard/bids-2-devel#96

Open

kabilar added 2 commits January 26, 2026 15:51

Update field names and units based on feedback

7af905f

Merge branch 'master' of https://github.com/bids-standard/bids-specif…

eb380c5

…ication into dwi-parameters

kabilar requested review from arokem, effigies and mharms January 26, 2026 21:54

mharms reviewed Jan 26, 2026

View reviewed changes

src/modality-specific-files/magnetic-resonance-imaging-data.md Outdated Show resolved Hide resolved

mharms reviewed Jan 26, 2026

View reviewed changes

Fix example

6851fa9

		"DiffGradientDuration": 11.0,
		"DiffGradientSeparation": 15.2,

	display_name: Diffusion Gradient Separation
	display_name: Diffusion Big Delta (Δ)

[ENH] Add DWI recommended metadata #2309

Are you sure you want to change the base?

[ENH] Add DWI recommended metadata #2309

Conversation

kabilar commented Jan 16, 2026

Uh oh!

codecov bot commented Jan 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

tsalo commented Jan 23, 2026

Uh oh!

mharms commented Jan 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

mharms commented Jan 23, 2026

Uh oh!

ayendiki commented Jan 23, 2026

Uh oh!

mharms commented Jan 23, 2026

Uh oh!

effigies commented Jan 23, 2026

Uh oh!

kabilar commented Jan 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

kabilar commented Jan 23, 2026

Uh oh!

kabilar commented Jan 23, 2026

Uh oh!

markmikkelsen commented Jan 24, 2026

Uh oh!

markmikkelsen commented Jan 24, 2026

Uh oh!

markmikkelsen commented Jan 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

effigies commented Jan 24, 2026

Uh oh!

kabilar commented Jan 26, 2026

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

7 participants

codecov bot commented Jan 16, 2026 •

edited

Loading

mharms commented Jan 23, 2026 •

edited

Loading

kabilar commented Jan 23, 2026 •

edited

Loading

markmikkelsen commented Jan 24, 2026 •

edited

Loading